PATHHardware Documentation > USB Devices > Mac OS USB DDK API Reference

USBGetFullConfigurationDescriptor

The USBGetFullConfigurationDescriptor function returns the entire block of configuration data from the specified device and any associated descriptors, which includes interface and endpoint descriptors, and all of the information that pertains to them. The configuration data returned by the USBGetFullConfigurationDescriptor function is suitable for use with the USBFindNextInterfaceDescriptorImmediate and the USBFindNextEndpointDescriptorImmediate functions.

Required fields in the USBPB parameter block for the USBGetFullConfigurationDescriptor function are

--> pbLength

Length of parameter block

--> pbVersion

Parameter block version number

--> usbCompletion

The completion routine

--> usbRefcon

General-purpose value passed back to the completion routine

--> usbFlags

Should be set to 0

--> usbReference

Device reference

--> usb.cntl.WValue

Configuration index

<-- usbBuffer

Points to a configuration descriptor structure

<-- usbActCount

Size of descriptor returned

The USBGetFullConfigurationDescriptor function determines the size of a full configuration descriptor, including all interface and endpoint descriptors for a given configuration, allocates memory for the configuration descriptor, and reads all the descriptors in.

You don't pass the USBGetFullConfigurationDescriptor function a buffer pointer, the function allocates one and passes a pointer back in the usbBuffer field of the parameter block. The memory for the configuration descriptor must be deallocated when the information is no longer needed. The USBDeallocMem function should be used in the class driver's finalize routine for deallocating memory and disposing of the descriptor.

The USBGetFullConfigurationDescriptor function is unusual in that it takes a configuration index in the usb.cntl.WValue field rather than a configuration value. The configuration value is found in the configuration descriptor, and is not available until the descriptor has been read. The configuration index refers to the 1st, 2nd, 3rd, or greater configuration descriptor in a device by specifying 0, 1, 2, or greater respectively. The configuration index is independent of the configuration value found in the configuration descriptor. The configuration value is used as an input parameter to set the configuration for a device.

Currently there are no other functions in the USB configuration services that provide the same functionality as the USBGetFullConfigurationDescriptor function. Configuration descriptors can be retrieved using the USBGetConfigurationDescriptor function, but the driver has to find the length of the configuration descriptor and allocate the memory for the descriptor when calling the function. Specific types of descriptors can be found with the USBFindNextAssociatedDescriptor function.

Once you have obtained the configuration descriptor, you need to find the interface you're interested in within the configuration descriptor by using the USBFindNextInterfaceDescriptorImmediate function.

Previous | Back Up One Level | Next | Show Frames | Hide Frames